app/api/research/career/route.ts (1)

5-7: Upgrade placeholder JSDoc to actual API documentation.

Line 5-Line 7 and Line 12-Line 15 should describe endpoint behavior and request expectations instead of empty placeholders.

As per coding guidelines, "app/api/**/route.ts: All API routes should have JSDoc comments".

Also applies to: 12-15

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/research/career/route.ts` around lines 5 - 7, Replace the empty JSDoc
blocks with real API documentation describing the route behavior and request
expectations: document the exported route handler functions (e.g., GET/POST
handlers in this file), the endpoint purpose, accepted request parameters/body
shape, expected response shape and status codes, and any authorization or error
cases; update both JSDoc blocks (lines around the top of the file and the later
block) so they clearly state input/output contracts and side effects to satisfy
the "app/api/**/route.ts: All API routes should have JSDoc comments" guideline.

app/api/research/curator/route.ts (2)

1-18: Consider a shared route-wrapper utility for research endpoints.

Line 8-Line 10 and Line 16-Line 17 follow the same passthrough pattern repeated across these new research routes. A small factory/helper would reduce repetition and keep future endpoint additions safer.

As per coding guidelines, "**/*.{ts,tsx}: Extract shared logic into reusable utilities following Don't Repeat Yourself (DRY) principle".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/research/curator/route.ts` around lines 1 - 18, The OPTIONS and GET
handlers in this file duplicate passthrough logic (calling getCorsHeaders and
delegating to getResearchCuratorHandler); factor this pattern into a reusable
route wrapper (e.g., a utility that builds standard handlers for research
endpoints) and replace the explicit OPTIONS and GET implementations with calls
to that wrapper; reference the existing symbols OPTIONS, GET, getCorsHeaders and
getResearchCuratorHandler when implementing the factory so it returns a standard
OPTIONS response with CORS headers and a GET handler that delegates to the
provided handler function.

---

5-7: Replace placeholder JSDoc with endpoint-level contract details.

The blocks at Line 5-Line 7 and Line 12-Line 15 are empty placeholders. Please document method intent, required query params, and key error cases.

Proposed doc-only update

-/**
- *
- */
+/**
+ * OPTIONS /api/research/curator
+ * Handles CORS preflight for the curator research endpoint.
+ */
 export async function OPTIONS() {
   return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
 }

-/**
- *
- * `@param` request
- */
+/**
+ * GET /api/research/curator
+ * Returns curator research data for the provided query parameters.
+ *
+ * `@param` request Incoming request with query params.
+ */
 export async function GET(request: NextRequest) {
   return getResearchCuratorHandler(request);
 }

As per coding guidelines, "app/api/**/route.ts: All API routes should have JSDoc comments".

Also applies to: 12-15

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/research/curator/route.ts` around lines 5 - 7, The file has empty
JSDoc placeholders for the API endpoint; replace each placeholder block with an
endpoint-level contract: a short description of intent, the HTTP method(s)
handled (e.g., GET/POST), required query parameters or body schema (names and
types), expected success response shape and status code, and key error cases
with their status codes (validation, auth, not-found, server errors). Update the
JSDoc immediately above the route handler functions (the exported GET/POST
handlers in app/api/research/curator/route.ts) so it documents required params,
example requests/responses, and any thrown errors.

app/api/research/lookup/route.ts (1)

5-7: Add substantive JSDoc for route contract clarity.

At Line 5-Line 7 and Line 12-Line 15, please replace empty placeholders with method intent, required params, and key error responses.

As per coding guidelines, "app/api/**/route.ts: All API routes should have JSDoc comments".

Also applies to: 12-15

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/research/lookup/route.ts` around lines 5 - 7, Add substantive JSDoc
above the exported route handler functions (e.g., the exported async GET/POST
handlers in this file) replacing the empty blocks: state the HTTP method and
high-level intent, list required query or body parameters (names, types, whether
optional), describe the successful response shape and status code (e.g., 200
with JSON { ... }), and enumerate key error responses and their status codes
(e.g., 400 for validation errors, 401/403 for auth, 404 if no resource, 500 for
server errors). Include any auth/permission requirements and examples of
expected input/output where helpful so the route contract is clear to callers
and maintainers.

lib/research/getResearchProfileHandler.ts (1)

7-9: Prefer provider-agnostic wording in endpoint docs.

Line 7 references “Chartmetric artist profile.” Since this API layer is intended to stay provider-agnostic, consider generic wording in the handler JSDoc.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/research/getResearchProfileHandler.ts` around lines 7 - 9, Update the
JSDoc for getResearchProfileHandler to remove provider-specific wording (remove
"Chartmetric") and use generic phrasing like "Returns the full artist profile"
or "Returns the full research artist profile" while keeping the note about
requiring the `artist` query param (name, numeric ID, or UUID); locate the JSDoc
comment above the getResearchProfileHandler function and replace the
provider-specific sentence with the provider-agnostic wording.

app/api/research/cities/route.ts (1)

5-7: Provide meaningful JSDoc for both handlers.

At Line 5-Line 7 and Line 12-Line 15, the comments are placeholders; add concrete method/param/response documentation.

Based on learnings, "Applies to app/api/**/route.ts : All API routes should have JSDoc comments".

Also applies to: 12-15

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/research/cities/route.ts` around lines 5 - 7, Replace the placeholder
comment blocks with meaningful JSDoc for each exported route handler: add a
JSDoc above export async function GET describing the endpoint purpose, accepted
query params, the shape of the returned JSON and possible status codes; add a
JSDoc above export async function POST describing the request body schema,
validation rules, created resource format, status codes (e.g., 201/400/500), and
any auth/permission requirements or thrown errors; ensure each JSDoc includes
`@param` for request/query/body, `@returns` for response shape and status, and
`@throws` (or `@throws`) for error cases so the handlers are fully documented.

app/api/research/similar/route.ts (1)

5-7: Replace placeholder comments with concrete JSDoc.

Line 5-Line 7 and Line 12-Line 15 should document endpoint behavior and required query semantics.

As per coding guidelines, "app/api/**/route.ts: All API routes should have JSDoc comments".

Also applies to: 12-15

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/research/similar/route.ts` around lines 5 - 7, The file contains
placeholder block comments; replace them with concrete JSDoc for the API route:
add a top-level JSDoc that describes the endpoint purpose (what "similar"
returns), accepted HTTP method(s) and example usage, and for the exported GET
handler (or any exported function named GET) add JSDoc describing required query
parameters (names, types, whether required), expected response shape and status
codes, and any error conditions; ensure the JSDoc explicitly documents required
query semantics (e.g., "q: string, required", "limit: number, optional, default
10") and update both comment blocks referenced (the header comment and the block
above the GET handler) accordingly.

app/api/research/discover/route.ts (1)

5-7: Fill in the JSDoc placeholders with real route docs.

Line 5-Line 7 and Line 12-Line 15 currently provide no contract detail. Please include endpoint purpose, required query params, and expected error statuses.

Based on learnings, "Applies to app/api/**/route.ts : All API routes should have JSDoc comments".

Also applies to: 12-15

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/research/discover/route.ts` around lines 5 - 7, Replace the empty
JSDoc blocks with a real route contract for the exported route handler (e.g.,
the GET handler or exported default function in this file): document the
endpoint purpose (what "discover" returns), list required and optional query
parameters by name and type (e.g., q: string, page: number, limit: number),
describe the successful response shape and status code (200 + JSON schema), and
enumerate expected error statuses and conditions (400 for bad request/missing
params, 401 for unauthorized, 500 for server errors) including example request
and response snippets; ensure the JSDoc tags `@route`, `@param`, `@returns`, and
`@throws/`@errors are present and match the handler function name (GET or default
export) so consumers know the contract.

app/api/research/route.ts (1)

8-10: Consider centralizing preflight response creation to reduce repeated route boilerplate.

OPTIONS() is duplicated across the new research routes; extracting a tiny helper/factory would reduce maintenance overhead and keep behavior uniform.

As per coding guidelines: **/*.{ts,tsx}: Extract shared logic into reusable utilities following Don't Repeat Yourself (DRY) principle.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/research/route.ts` around lines 8 - 10, Extract the duplicated
preflight response creation into a reusable helper (e.g., preflightResponse or
createPreflightResponse) that returns new NextResponse(null, { status: 200,
headers: getCorsHeaders() }) and replace each route's OPTIONS() implementation
with a single call to that helper; ensure the helper imports/uses getCorsHeaders
and NextResponse so all research routes call the same function for uniform CORS
preflight handling.

app/api/research/profile/route.ts (1)

5-7: Document this route with meaningful JSDoc (not placeholder blocks).

Lines 5-7 and Lines 12-15 should describe preflight behavior and the GET contract so the route is self-explanatory.

📝 Proposed doc update

 /**
- *
+ * OPTIONS /api/research/profile
+ *
+ * Handles CORS preflight for the profile research endpoint.
  */
 export async function OPTIONS() {
   return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
 }
 
 /**
- *
+ * GET /api/research/profile
+ *
+ * Returns profile-level research data for the requested artist.
+ *
  * `@param` request
  */
 export async function GET(request: NextRequest) {
   return getResearchProfileHandler(request);
 }

Based on learnings: Applies to app/api/**/route.ts : All API routes should have JSDoc comments.

Also applies to: 12-15

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/research/profile/route.ts` around lines 5 - 7, Replace the
placeholder JSDoc in app/api/research/profile/route.ts with a concise,
meaningful comment that documents preflight behavior and the GET contract: state
that the route responds to OPTIONS preflight with appropriate CORS headers (if
applicable) and that the exported GET function accepts any query or auth
requirements (e.g., required headers, session) and returns JSON describing the
user profile, list the expected response shape (fields and types), possible
status codes (200, 401, 400, 500) and error conditions, and note content-type
and any caching or rate-limit behavior; reference the exported GET handler name
and any helper functions used so a reader can find the implementation quickly.

app/api/research/playlist/route.ts (1)

5-7: Replace empty JSDoc blocks with endpoint-specific descriptions.

Lines 5-7 and Lines 12-15 currently don’t document behavior, params, or intent.

📝 Proposed doc update

 /**
- *
+ * OPTIONS /api/research/playlist
+ *
+ * Handles CORS preflight for the playlist research endpoint.
  */
 export async function OPTIONS() {
   return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
 }
 
 /**
- *
+ * GET /api/research/playlist
+ *
+ * Returns playlist-level research data for the requested playlist context.
+ *
  * `@param` request
  */
 export async function GET(request: NextRequest) {
   return getResearchPlaylistHandler(request);
 }

As per coding guidelines: app/api/**/route.ts: All API routes should have JSDoc comments.

Also applies to: 12-15

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/research/playlist/route.ts` around lines 5 - 7, Replace the empty
JSDoc blocks above the route handler functions with concise, endpoint-specific
JSDoc for the exported handlers (e.g., GET and POST functions) that describes
the endpoint purpose, accepted parameters or request body shape, expected
response shape/status codes, authentication/authorization requirements, and
possible error conditions; update the two blank comment blocks to include
summary, `@param` for Request/NextRequest where applicable, `@returns` for
Response/NextResponse, and any side effects so future readers and automated
linters have meaningful documentation.

app/api/research/genres/route.ts (1)

5-7: Fill in the JSDoc placeholders with actual route contract details.

Lines 5-7 and Lines 12-15 are empty blocks today, which makes the route self-documentation effectively missing.

📝 Proposed doc update

 /**
- *
+ * OPTIONS /api/research/genres
+ *
+ * Handles CORS preflight for the genres research endpoint.
  */
 export async function OPTIONS() {
   return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
 }
 
 /**
- *
+ * GET /api/research/genres
+ *
+ * Returns available genres from the research provider.
+ *
  * `@param` request
  */
 export async function GET(request: NextRequest) {
   return getResearchGenresHandler(request);
 }

As per coding guidelines: app/api/**/route.ts: All API routes should have JSDoc comments.

Also applies to: 12-15

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/research/genres/route.ts` around lines 5 - 7, Replace the empty JSDoc
blocks in this route with concrete contract details: update the top-of-file
JSDoc (first empty block) to include a short description of the route purpose,
HTTP method(s) it supports, expected path, authorization requirements, and
primary response shape; then update the second empty JSDoc (lines 12-15)
immediately above the exported handler/function to document parameters
(path/query/body), example request/response types or status codes, and any error
conditions. Reference the route's exported handler (the default export or the
named GET/POST function in this file) and ensure the JSDoc contains method,
input contract, and output contract so the route is fully self-documented.

app/api/research/metrics/route.ts (1)

1-18: Consider extracting a shared research route factory to reduce boilerplate.

This route repeats the same OPTIONS + delegated GET structure used across many files; centralizing it will reduce copy/paste drift.

♻️ Refactor sketch

-import { NextRequest, NextResponse } from "next/server";
-import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { createResearchGetRoute } from "@/lib/research/createResearchGetRoute";
 import { getResearchMetricsHandler } from "@/lib/research/getResearchMetricsHandler";

-/**
- *
- */
-export async function OPTIONS() {
-  return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
-}
-
-/**
- *
- * `@param` request
- */
-export async function GET(request: NextRequest) {
-  return getResearchMetricsHandler(request);
-}
+export const { OPTIONS, GET } = createResearchGetRoute(getResearchMetricsHandler);

// lib/research/createResearchGetRoute.ts
import { NextRequest, NextResponse } from "next/server";
import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";

export function createResearchGetRoute(
  handler: (request: NextRequest) => Promise<NextResponse>,
) {
  return {
    async OPTIONS() {
      return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
    },
    async GET(request: NextRequest) {
      return handler(request);
    },
  };
}

As per coding guidelines "**/*.{ts,tsx}: Extract shared logic into reusable utilities following Don't Repeat Yourself (DRY) principle".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/research/metrics/route.ts` around lines 1 - 18, This route duplicates
the common OPTIONS + delegated GET pattern; extract a reusable factory (e.g.,
createResearchGetRoute) that returns { async OPTIONS() { return new
NextResponse(null, { status: 200, headers: getCorsHeaders() }); }, async
GET(request) { return handler(request); } } and update this file to export the
result of createResearchGetRoute(getResearchMetricsHandler) so OPTIONS and GET
behavior is centralized; reference getCorsHeaders, createResearchGetRoute, and
getResearchMetricsHandler when making the change.

app/api/research/audience/route.ts (1)

5-17: Empty JSDoc comments need documentation.

Same pattern as other route files. Add meaningful descriptions for the audience endpoint's purpose and parameters.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/research/audience/route.ts` around lines 5 - 17, Add meaningful JSDoc
comments above the OPTIONS and GET exports to describe the endpoint's purpose
and behavior: document that OPTIONS returns CORS preflight with getCorsHeaders
and that GET accepts a NextRequest and delegates to getResearchAudienceHandler
to retrieve research audience data; include descriptions of parameters (request:
NextRequest), return values (NextResponse), and any side effects or headers so
the comments match the style used in other route files.

app/api/research/albums/route.ts (1)

5-17: Empty JSDoc comments need meaningful descriptions.

The JSDoc blocks are present but lack any actual documentation. As per coding guidelines, all API routes should have descriptive JSDoc comments explaining the endpoint's purpose, expected parameters, and response structure.

📝 Suggested JSDoc improvements

-/**
- *
- */
+/**
+ * Handles CORS preflight requests for the albums endpoint.
+ * `@returns` Empty response with CORS headers.
+ */
 export async function OPTIONS() {
   return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
 }

-/**
- *
- * `@param` request
- */
+/**
+ * GET /api/research/albums
+ * Retrieves album data for a given artist from Chartmetric.
+ * Requires `artist` query parameter.
+ *
+ * `@param` request - The incoming Next.js request object
+ * `@returns` JSON response with album data or error
+ */
 export async function GET(request: NextRequest) {
   return getResearchAlbumsHandler(request);
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/research/albums/route.ts` around lines 5 - 17, Replace the empty
JSDoc blocks above the exported OPTIONS and GET functions with descriptive
comments: document OPTIONS to explain it responds to preflight CORS checks,
returns a 200 with headers from getCorsHeaders(), and mention any headers set;
document GET to describe that it accepts a NextRequest, calls
getResearchAlbumsHandler(request) to fetch research album data, outline expected
query parameters (if any), possible response shapes and status codes, and note
that it uses NextRequest/NextResponse types; place these JSDoc comments
immediately above the OPTIONS and GET function declarations to satisfy
documentation guidelines.

app/api/research/festivals/route.ts (1)

5-17: Empty JSDoc comments—same pattern as other routes.

Populate the JSDoc blocks with meaningful endpoint documentation describing the festivals endpoint purpose and required parameters.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/research/festivals/route.ts` around lines 5 - 17, Replace the empty
JSDoc blocks above the OPTIONS and GET functions with descriptive endpoint
documentation: for OPTIONS describe this endpoint supports CORS preflight and
returns 200 with CORS headers; for GET document the festivals endpoint purpose
(returns research festivals list), accepted inputs (the NextRequest/query
parameters like page, limit, filters or any expected headers/auth token),
response shape (summary of returned data items and status codes), and any
errors; reference the GET function and getResearchFestivalsHandler to ensure the
documented parameters match what that handler reads.

app/api/research/instagram-posts/route.ts (1)

5-17: Empty JSDoc comments need meaningful descriptions.

Same issue as other route files—the JSDoc blocks are scaffolded but empty. Consider documenting the endpoint's purpose and the artist query parameter requirement.

📝 Suggested JSDoc improvements

-/**
- *
- */
+/**
+ * Handles CORS preflight requests for the Instagram posts endpoint.
+ */
 export async function OPTIONS() {
   return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
 }

-/**
- *
- * `@param` request
- */
+/**
+ * GET /api/research/instagram-posts
+ * Returns recent Instagram posts for the given artist via Chartmetric's DeepSocial integration.
+ * Requires `artist` query parameter.
+ *
+ * `@param` request - The incoming Next.js request object
+ */
 export async function GET(request: NextRequest) {
   return getResearchInstagramPostsHandler(request);
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/research/instagram-posts/route.ts` around lines 5 - 17, The JSDoc
blocks above the OPTIONS and GET handlers are empty; update them to document the
endpoint purpose and parameters: add a meaningful description for the OPTIONS()
function stating it returns CORS preflight responses, and for GET(request:
NextRequest) describe that it handles fetching research Instagram posts,
requires an "artist" query parameter (describe expected format and behavior),
and that it delegates to getResearchInstagramPostsHandler; reference the
functions OPTIONS, GET, and getResearchInstagramPostsHandler in the docs so
readers know where the logic lives.

app/api/research/insights/route.ts (1)

5-17: Empty JSDoc comments require documentation.

Fill in the JSDoc blocks to describe the insights endpoint—what noteworthy insights it returns and the required artist parameter.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/research/insights/route.ts` around lines 5 - 17, The file contains
empty JSDoc blocks above the exported handlers OPTIONS and GET; update them to
document the insights endpoint by describing what notable insights the GET
handler returns (e.g., trend summaries, top tracks, listener demographics, or
other research insights) and the required query or route parameter "artist" that
the endpoint expects; add brief descriptions for the OPTIONS function (returns
CORS headers and 200) and for GET (accepts a NextRequest, validates the required
artist parameter, and delegates to getResearchInsightsHandler), referencing the
functions OPTIONS, GET, getResearchInsightsHandler, and getCorsHeaders so
maintainers can locate and understand the behavior.

lib/research/proxyToChartmetric.ts (1)

48-50: Consider wrapping JSON parsing in try/catch.

response.json() can throw if the response body isn't valid JSON, which would result in an unhandled exception rather than a structured error response.

🛡️ Defensive JSON parsing

-  const json = await response.json();
-
-  const data = json.obj !== undefined ? json.obj : json;
+  let json: unknown;
+  try {
+    json = await response.json();
+  } catch {
+    return {
+      data: { error: "Invalid JSON response from Chartmetric" },
+      status: 502,
+    };
+  }
+
+  const data = typeof json === "object" && json !== null && "obj" in json
+    ? (json as { obj: unknown }).obj
+    : json;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/research/proxyToChartmetric.ts` around lines 48 - 50, Wrap the call to
response.json() in a try/catch inside proxyToChartmetric (around the lines
creating json and data) to avoid unhandled exceptions; if JSON parsing fails,
catch the error (e.g., SyntaxError), log or attach the parsing error and the raw
response text, and return or throw a structured error object/response instead of
letting the exception bubble (ensure downstream code that uses json/data handles
this error shape). Make sure to preserve existing behavior when parsing succeeds
by assigning json to data as currently done.

lib/research/resolveArtist.ts (1)

12-13: JSDoc return description doesn't match actual return type.

The docstring says "or null if not found" but the function returns { error: string } on failure, not null. The actual discriminated union return type is correct and well-designed.

📝 Fix documentation

- * `@returns` The Chartmetric artist ID, or null if not found
+ * `@returns` Object with `id` on success, or `error` message on failure

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/research/resolveArtist.ts` around lines 12 - 13, The JSDoc for
resolveArtist is inaccurate: it states the function returns "The Chartmetric
artist ID, or null if not found" but the implementation returns a discriminated
union that includes an error object ({ error: string }). Update the `@returns`
description in the resolveArtist JSDoc to accurately describe the actual return
shape (e.g., success result containing the Chartmetric artist ID or a failure
object with an error string), referencing the resolveArtist function and its
union return type so the docs match the implementation.

lib/research/getResearchCuratorHandler.ts (2)

39-39: Validate platform and id parameters before path interpolation.

User-controlled values are directly embedded in the API path. While id should be alphanumeric and platform should match known values, there's no validation enforcing this. Consider validating platform against an allowlist and ensuring id contains only expected characters.

🛡️ Suggested validation

+const VALID_CURATOR_PLATFORMS = ["spotify", "applemusic", "deezer"] as const;
+
 export async function getResearchCuratorHandler(request: NextRequest): Promise<NextResponse> {
   // ... auth validation ...

   const { searchParams } = new URL(request.url);
   const platform = searchParams.get("platform");
   const id = searchParams.get("id");

   if (!platform || !id) {
     return NextResponse.json(
       { status: "error", error: "platform and id parameters are required" },
       { status: 400, headers: getCorsHeaders() },
     );
   }

+  if (!VALID_CURATOR_PLATFORMS.includes(platform as typeof VALID_CURATOR_PLATFORMS[number])) {
+    return NextResponse.json(
+      { status: "error", error: `Invalid platform. Must be one of: ${VALID_CURATOR_PLATFORMS.join(", ")}` },
+      { status: 400, headers: getCorsHeaders() },
+    );
+  }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/research/getResearchCuratorHandler.ts` at line 39, In
getResearchCuratorHandler, validate the incoming platform and id before
interpolating them into the path passed to proxyToChartmetric: enforce platform
against a small allowlist (e.g., known enum values) and ensure id matches an
expected regex (alphanumeric, hyphen/underscore if allowed) and reject or return
a 400 error for invalid inputs; only after validation construct the path
`/curator/${platform}/${id}` and call proxyToChartmetric so no unvalidated
user-controlled characters reach the backend.

---

14-57: Consider extracting shared handler logic for non-artist lookups.

This handler duplicates the auth → credits → proxy → response pattern found in getResearchGenresHandler, getResearchFestivalsHandler, and others. A shared utility similar to handleArtistResearch but for non-artist lookups could reduce boilerplate. As per coding guidelines, "Extract shared logic into reusable utilities following Don't Repeat Yourself (DRY) principle."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/research/getResearchCuratorHandler.ts` around lines 14 - 57,
getResearchCuratorHandler duplicates the auth→credits→proxy→response flow used
by getResearchGenresHandler, getResearchFestivalsHandler, etc.; extract that
shared flow into a new utility (e.g., handleNonArtistResearch or
handleResearchLookup) that accepts parameters for building the proxy path (or a
path template), creditsToDeduct, and any response shaping, then update
getResearchCuratorHandler to call this utility instead of inlining
validateAuthContext, deductCredits, proxyToChartmetric and getCorsHeaders logic;
reuse the same utility from getResearchGenresHandler/getResearchFestivalsHandler
and leave handleArtistResearch untouched for artist-specific differences.

lib/research/getResearchPlaylistsHandler.ts (1)

20-25: Validate platform and status against an allowlist before path interpolation.

User-controlled values are directly embedded into the Chartmetric API path without validation. This pattern (also present in getResearchMetricsHandler.ts) could allow path injection if unexpected characters are passed. While the URL constructor provides some protection, explicit validation is safer and more defensive.

🛡️ Suggested validation

+const VALID_PLATFORMS = ["spotify", "applemusic", "deezer", "amazon", "itunes"] as const;
+const VALID_STATUSES = ["current", "past"] as const;
+
 export async function getResearchPlaylistsHandler(request: NextRequest) {
   const { searchParams } = new URL(request.url);
-  const platform = searchParams.get("platform") || "spotify";
-  const status = searchParams.get("status") || "current";
+  const platformParam = searchParams.get("platform") || "spotify";
+  const statusParam = searchParams.get("status") || "current";
+
+  const platform = VALID_PLATFORMS.includes(platformParam as typeof VALID_PLATFORMS[number])
+    ? platformParam
+    : "spotify";
+  const status = VALID_STATUSES.includes(statusParam as typeof VALID_STATUSES[number])
+    ? statusParam
+    : "current";

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/research/getResearchPlaylistsHandler.ts` around lines 20 - 25, Validate
the user-controlled platform and status before interpolating them into the
Chartmetric path: in getResearchPlaylistsHandler.ts (and similarly in
getResearchMetricsHandler.ts) replace the current unvalidated platform and
status usage by checking the platform and status variables against explicit
allowlists (e.g., ALLOWED_PLATFORMS and ALLOWED_STATUSES), and if a value is not
allowed either coerce to a safe default (e.g., "spotify"/"current") or return a
400 error; do this check before calling handleArtistResearch and use the
validated values when building the cmId =>
`/artist/${cmId}/${platform}/${status}/playlists` path. Ensure the validation
uses the exact variable names platform and status so the substitution is always
from trusted values.

lib/research/getResearchPlaylistHandler.ts (1)

19-39: Validate platform and id parameters to prevent path injection.

Same concern as getResearchCuratorHandler - user-controlled values are directly interpolated into the API path on line 39. The platform should be validated against known streaming platforms, and id should be validated to contain only alphanumeric characters or hyphens.

🛡️ Suggested validation

+const VALID_PLAYLIST_PLATFORMS = ["spotify", "applemusic", "deezer", "amazon"] as const;
+const PLAYLIST_ID_PATTERN = /^[\w-]+$/;
+
 // After presence check:
+  if (!VALID_PLAYLIST_PLATFORMS.includes(platform as typeof VALID_PLAYLIST_PLATFORMS[number])) {
+    return NextResponse.json(
+      { status: "error", error: "Invalid platform" },
+      { status: 400, headers: getCorsHeaders() },
+    );
+  }
+
+  if (!PLAYLIST_ID_PATTERN.test(id)) {
+    return NextResponse.json(
+      { status: "error", error: "Invalid playlist ID format" },
+      { status: 400, headers: getCorsHeaders() },
+    );
+  }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/research/getResearchPlaylistHandler.ts` around lines 19 - 39, Validate
incoming query params in getResearchPlaylistHandler before calling
proxyToChartmetric: ensure platform matches a whitelist of known streaming
platforms (e.g., an array like ["spotify","apple","youtube","deezer"]) and
ensure id matches a strict pattern (only alphanumerics, hyphens, underscores or
whatever spec you choose, e.g., /^[A-Za-z0-9_-]+$/). If either check fails
return a 400 NextResponse with an error message and CORS headers (same shape
used elsewhere). Only after both validations pass call
proxyToChartmetric(`/playlist/${platform}/${id}`) so untrusted input cannot
inject paths. Ensure the validation is done prior to deductCredits or bail out
early as appropriate.

lib/research/getResearchLookupHandler.ts (2)

61-69: Response spreading pattern is duplicated across handlers.

This exact pattern (typeof result.data === "object" && result.data !== null ? result.data : { data: result.data }) appears in multiple handlers. Consider extracting a shared utility like formatProxyResponse(result) to consolidate this logic.

♻️ Suggested utility extraction

Create a shared utility in lib/research/formatProxyResponse.ts:

export function formatProxyResponse(data: unknown): Record<string, unknown> {
  return typeof data === "object" && data !== null
    ? (data as Record<string, unknown>)
    : { data };
}

Then simplify handlers:

+import { formatProxyResponse } from "@/lib/research/formatProxyResponse";

 return NextResponse.json(
-    {
-      status: "success",
-      ...(typeof result.data === "object" && result.data !== null
-        ? result.data
-        : { data: result.data }),
-    },
+    { status: "success", ...formatProxyResponse(result.data) },
     { status: 200, headers: getCorsHeaders() },
 );

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/research/getResearchLookupHandler.ts` around lines 61 - 69, The
response-spreading logic repeated in getResearchLookupHandler (the ternary
checking typeof result.data === "object" && result.data !== null and spreading
result.data or wrapping it as { data: result.data }) should be extracted to a
shared utility (e.g., formatProxyResponse) and used where NextResponse.json is
called; create a function like formatProxyResponse(data: unknown):
Record<string, unknown> that returns data if it's a non-null object or { data }
otherwise, then replace the inline ternary in the NextResponse.json call (and
other handlers using the same pattern) with formatProxyResponse(result.data) to
centralize the logic.

---

43-50: Same catch block observation as the search handler.

Consider differentiating between "No credits usage found" and "Insufficient credits" errors from deductCredits for better error messaging.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/research/getResearchLookupHandler.ts` around lines 43 - 50, The catch
block calling deductCredits in getResearchLookupHandler should capture the
thrown error (catch (err)) and distinguish between a "No credits usage found"
error and an "Insufficient credits" error (by checking err.code or err.message
or a custom error class from deductCredits); return a 404/appropriate status and
JSON {status:"error", error:"No credits usage found"} when the no-usage
condition is detected, otherwise return the 402 JSON {status:"error",
error:"Insufficient credits"} for insufficient funds—update deductCredits usage
handling accordingly so responses accurately reflect the error type.

lib/research/getResearchSearchHandler.ts (1)

31-38: Catch block masks error details.

The catch block assumes all errors from deductCredits mean "Insufficient credits," but per lib/credits/deductCredits.ts, it may also throw "No credits usage found for this account." Logging or differentiating the error message would improve debuggability.

💡 Suggested improvement

   try {
     await deductCredits({ accountId, creditsToDeduct: 5 });
-  } catch {
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Insufficient credits";
     return NextResponse.json(
-      { status: "error", error: "Insufficient credits" },
+      { status: "error", error: message },
       { status: 402, headers: getCorsHeaders() },
     );
   }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/research/getResearchSearchHandler.ts` around lines 31 - 38, The catch
block in getResearchSearchHandler around the call to deductCredits currently
swallows the thrown error and always returns "Insufficient credits"; change it
to catch the error object (e), log or include e.message, and branch on e.message
(or error type) from deductCredits to return an appropriate response (e.g., 402
for insufficient credits, a 4xx/404 for "No credits usage found for this
account") while ensuring getCorsHeaders() is preserved; update the handler's
error response to include the actual error message for better debuggability.

lib/research/getResearchDiscoverHandler.ts (2)

26-33: Same catch block observation applies here.

The catch block masks the specific error from deductCredits. Consider preserving error details as suggested in the other handlers.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/research/getResearchDiscoverHandler.ts` around lines 26 - 33, Change the
catch to capture the thrown error from deductCredits (e.g., catch (err)) and
include the error details when returning the NextResponse.json so the client and
logs preserve the underlying reason; update the response payload returned by
NextResponse.json in getResearchDiscoverHandler to include the actual error
message (err.message or String(err)) alongside "Insufficient credits" and, if
available in this module, log the full error via the existing logger before
returning, keeping the CORS headers from getCorsHeaders().

---

64-72: Same response spreading pattern—consolidation opportunity.

This is the same spreading logic seen in the other handlers. A shared formatProxyResponse utility would reduce duplication.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/research/getResearchDiscoverHandler.ts` around lines 64 - 72, The
response construction in getResearchDiscoverHandler.ts duplicates the spreading
logic used elsewhere when returning NextResponse.json (specifically the
conditional spread of result.data vs { data: result.data }); extract this into a
shared utility (e.g., formatProxyResponse) that accepts the proxy result and
returns the normalized response body, then replace the inline spreading in
getResearchDiscoverHandler (and other handlers) to call formatProxyResponse and
pass its result into NextResponse.json with the existing status and headers.

lib/research/getResearchTrackHandler.ts (2)

16-82: Handler exceeds 50-line guideline and performs two distinct operations.

This handler orchestrates search + detail fetch, making it longer than the 50-line limit and arguably violating SRP. Consider splitting into smaller functions or creating a searchAndFetchTrack helper.

♻️ Suggested decomposition

// In a separate file or as local helpers:
async function searchTrackByName(q: string): Promise<{ trackId: number } | null> {
  const result = await proxyToChartmetric("/search", { q, type: "tracks", limit: "1" });
  if (result.status !== 200) return null;
  const data = result.data as { tracks?: Array<{ id: number }> };
  return data?.tracks?.[0] ? { trackId: data.tracks[0].id } : null;
}

async function fetchTrackDetails(trackId: number): Promise<ProxyResult> {
  return proxyToChartmetric(`/track/${trackId}`);
}

This keeps the main handler focused on orchestration and error responses.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/research/getResearchTrackHandler.ts` around lines 16 - 82, The
getResearchTrackHandler is too long and mixes two responsibilities (search +
detail fetch); extract the search and detail-fetch logic into helpers (e.g.,
create searchTrackByName(q: string) that calls proxyToChartmetric("/search", {
q, type: "tracks", limit: "1" }) and returns a trackId or null, and
fetchTrackDetails(trackId: number) that calls
proxyToChartmetric(`/track/${trackId}`) ), then simplify getResearchTrackHandler
to validate auth, call deductCredits, call searchTrackByName to get trackId,
handle not-found/error responses, then call fetchTrackDetails and return the
final response; keep existing error responses and headers (getCorsHeaders) and
preserve calls to validateAuthContext and deductCredits.

---

31-38: Credits deducted before API calls complete.

Credits are deducted at line 32, but two sequential API calls follow. If the search succeeds but the detail fetch fails (rate limit, timeout, etc.), the user loses credits without receiving the track details. This is a known tradeoff (per context snippets), but worth documenting or considering a deferred-deduction pattern for multi-call handlers.

Also applies to: 40-51, 63-71

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/research/getResearchTrackHandler.ts` around lines 31 - 38, deductCredits
is called before the subsequent external API calls, so if the search succeeds
but the detail fetch fails the user still loses credits; change
getResearchTrackHandler to either defer calling deductCredits until after all
dependent API calls (e.g., after search+detail fetch succeed) or implement a
compensating refund flow by calling a refundCredits/{creditRefund} helper when
the detail fetch fails, and ensure the error path that returns
NextResponse.json({ status: "error", ... }, { status: 402, headers:
getCorsHeaders() }) triggers that refund; locate usages of deductCredits and the
error return blocks (the try/catch around deductCredits and the later failure
branches) and update them to use the deferred-deduction or refund approach
consistently for the other similar blocks noted (lines 40-51, 63-71).

lib/research/getResearchPlaylistHandler.ts (1)

14-81: This handler is doing too much in one place.

Auth, param validation, credit deduction, non-numeric ID resolution, upstream proxying, and response shaping are all packed into one 68-line function. Extracting something like resolvePlaylistId() plus a small shared error-response helper would make the branches easier to test and keep this closer to the repo's handler conventions.

As per coding guidelines, lib/**/*.ts: Apply Single Responsibility Principle (SRP): one exported function per file; each file should do one thing well and For domain functions, ensure: Single responsibility per function, Keep functions under 50 lines, and DRY: Consolidate similar logic into shared utilities.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/research/getResearchPlaylistHandler.ts` around lines 14 - 81,
getResearchPlaylistHandler is doing too many responsibilities; split its logic
by extracting a resolvePlaylistId(requestPlatform, id, proxyToChartmetric)
function to encapsulate the non-numeric ID lookup and playlistId resolution, and
add a small helper like makeErrorResponse(payload, status) to centralize JSON
error responses (used instead of repeating NextResponse.json(..., { headers:
getCorsHeaders() })). Move the existing credit check (deductCredits), auth
(validateAuthContext), and final proxy call
(proxyToChartmetric(`/playlist/${platform}/${playlistId}`)) to orchestrate these
smaller functions so getResearchPlaylistHandler becomes a thin coordinator under
50 lines, reusing resolvePlaylistId and makeErrorResponse for testable,
single-responsibility units while preserving existing symbols:
validateAuthContext, deductCredits, proxyToChartmetric, getCorsHeaders.

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

lib/research/getResearchDiscoverHandler.ts (1)

50-53: ⚠️ Potential issue | 🟠 Major

Bug: sp_ml[] min value is lost when both bounds are specified.

This issue was previously flagged and remains unresolved. When both mlMin and mlMax are provided, line 53 overwrites line 52's assignment because proxyToChartmetric uses url.searchParams.set() (which replaces rather than appends). Only the max listener bound reaches Chartmetric, effectively breaking the range filter.

Two options to fix:

1. Modify proxyToChartmetric to accept Record<string, string | string[]> and use append() for array values
2. Build the URL differently in this handler if Chartmetric expects a different format (comma-separated, etc.)

🔧 Option 1: Update proxyToChartmetric signature

In lib/research/proxyToChartmetric.ts:

 export async function proxyToChartmetric(
   path: string,
-  queryParams?: Record<string, string>,
+  queryParams?: Record<string, string | string[]>,
 ): Promise<ProxyResult> {
   // ...
   if (queryParams) {
     for (const [key, value] of Object.entries(queryParams)) {
-      if (value !== undefined && value !== "") {
-        url.searchParams.set(key, value);
+      if (value !== undefined && value !== "") {
+        if (Array.isArray(value)) {
+          for (const v of value) {
+            url.searchParams.append(key, v);
+          }
+        } else {
+          url.searchParams.set(key, value);
+        }
       }
     }
   }

Then in this handler:

   const mlMin = searchParams.get("sp_monthly_listeners_min");
   const mlMax = searchParams.get("sp_monthly_listeners_max");
-  if (mlMin) params["sp_ml[]"] = mlMin;
-  if (mlMax) params["sp_ml[]"] = mlMax;
+  const mlValues = [mlMin, mlMax].filter(Boolean) as string[];
+  if (mlValues.length > 0) params["sp_ml[]"] = mlValues;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/research/getResearchDiscoverHandler.ts` around lines 50 - 53, The handler
is overwriting the sp_ml[] param when both mlMin and mlMax are present because
proxyToChartmetric uses url.searchParams.set(); update proxyToChartmetric to
accept Record<string, string | string[]> and, when a value is an array, call
url.searchParams.append() for each element, then in getResearchDiscoverHandler
(symbols: mlMin, mlMax, params and params["sp_ml[]"]) set params["sp_ml[]"] =
[mlMin, mlMax] (or a single string when only one bound exists) so both bounds
are sent to Chartmetric.

lib/research/postResearchDeepHandler.ts (1)

15-71: Extract shared POST research orchestration into a reusable utility.

This handler repeats the same auth → parse → validate → deduct → execute → map-error pattern used in other research POST handlers. Consolidating this flow will reduce drift and fix bugs once.

As per coding guidelines: "Extract shared logic into reusable utilities following Don't Repeat Yourself (DRY) principle."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/research/postResearchDeepHandler.ts` around lines 15 - 71, Extract the
repeated auth→parse→validate→deduct→execute→map-error flow from
postResearchDeepHandler into a reusable utility (e.g.,
handlePostResearchRequest) that accepts the NextRequest, creditsToDeduct, an
executor callback (the core execution like chatWithPerplexity), and any
operation name for logs; move the calls to validateAuthContext, request.json
parsing, query presence check, deductCredits, and unified NextResponse creation
(preserving getCorsHeaders and the same status codes for 400/402/500/200) into
that utility, then refactor postResearchDeepHandler to call this utility with
creditsToDeduct=25 and an executor that invokes chatWithPerplexity([{ role:
"user", content: body.query }], "sonar-deep-research") and maps the executor
result to the { status:"success", content, citations } shape while letting the
utility handle error mapping.

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

app/api/research/venues/route.ts-5-15 (1)

5-15: ⚠️ Potential issue | 🟡 Minor

Empty JSDoc comments need meaningful documentation.

The JSDoc blocks are present but contain no actual documentation. Per coding guidelines, all API routes should have JSDoc comments that describe the endpoint's purpose, parameters, and response.

📝 Proposed documentation

 /**
- *
+ * Handles CORS preflight requests for the venues endpoint.
+ * `@returns` Empty response with CORS headers
  */
 export async function OPTIONS() {
   return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
 }

 /**
- *
- * `@param` request
+ * Returns venues the artist has performed at, including capacity and location.
+ * Requires `artist` query parameter (name or UUID).
+ * `@param` request - The incoming Next.js request
+ * `@returns` Venue data for the specified artist
  */
 export async function GET(request: NextRequest) {

As per coding guidelines: "All API routes should have JSDoc comments".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/research/venues/route.ts` around lines 5 - 15, The empty JSDoc blocks
above the OPTIONS export (function OPTIONS) and the following handler parameter
should be replaced with meaningful documentation: add a brief description of the
endpoint's purpose, document the request parameter (type and expected shape or
headers), and describe the response (status codes and headers, e.g., CORS
preflight 200 with getCorsHeaders()). Update the JSDoc for function OPTIONS and
the subsequent handler's JSDoc to follow the project's JSDoc style and include
`@param` and `@returns` tags so the route's behavior is clear.

lib/research/getResearchRankHandler.ts-16-16 (1)

16-16: ⚠️ Potential issue | 🟡 Minor

Use nullish coalescing and a typed payload for rank.

Line 16 uses || null, which can coerce valid falsy values, and as any drops type safety.

Proposed fix

-    (data) => ({ rank: (data as any)?.artist_rank || null }),
+    (data) => {
+      const rank = (data as { artist_rank?: number | null })?.artist_rank ?? null;
+      return { rank };
+    },

As per coding guidelines lib/**/*.ts: "Use TypeScript for type safety".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/research/getResearchRankHandler.ts` at line 16, Replace the unsafe cast
and falsy-coercing fallback in the mapping that returns { rank: ... } by
introducing a typed payload (e.g., an interface like ResearchRankPayload with
artist_rank?: number | null) and using a safe nullish coalescing fallback;
specifically, change the occurrence of (data as any)?.artist_rank || null to a
typed access (data as ResearchRankPayload)?.artist_rank ?? null inside the
mapping used by getResearchRankHandler so valid falsy values (0, '') are
preserved and you regain compile-time type safety.

lib/mcp/tools/research/registerResearchPeopleTool.ts-9-13 (1)

9-13: ⚠️ Potential issue | 🟡 Minor

Add integer bounds to the num_results schema.

The Zod schema accepts any number, but searchPeople documents a maximum of 100 results. Without bounds validation, invalid or oversized requests could reach the upstream Exa API. Add .int(), .min(1), and .max(100) constraints to enforce valid input at the MCP tool boundary.

Proposed fix

   num_results: z
     .number()
+    .int()
+    .min(1)
+    .max(100)
     .optional()
     .default(10)
     .describe("Number of results to return (default: 10)"),

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/mcp/tools/research/registerResearchPeopleTool.ts` around lines 9 - 13,
Update the Zod schema for num_results to enforce integer bounds so oversized or
invalid requests are blocked at the MCP boundary: change the num_results
definition that currently uses z.number() to include .int().min(1).max(100)
(keeping .optional().default(10) and .describe("Number of results to return
(default: 10)") intact) so the schema validates integer values between 1 and 100
for num_results before calling searchPeople.

app/api/research/radio/route.ts-5-10 (1)

5-10: ⚠️ Potential issue | 🟡 Minor

Empty JSDoc comments should be populated.

Per coding guidelines, all API routes should have JSDoc comments. These are empty and don't provide documentation value.

📝 Suggested documentation

 /**
- *
+ * CORS preflight handler for /api/research/radio
  */
 export async function OPTIONS() {
   return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/research/radio/route.ts` around lines 5 - 10, Populate the empty
JSDoc for the OPTIONS handler by adding a concise description of its purpose and
behavior, parameters (none), and return type; update the comment above export
async function OPTIONS() to explain that it responds to CORS preflight requests,
returns a 200 NextResponse with CORS headers from getCorsHeaders(), and note any
side effects or relevant headers used so callers and maintainers understand the
route.

app/api/research/radio/route.ts-12-18 (1)

12-18: ⚠️ Potential issue | 🟡 Minor

Populate JSDoc with endpoint description.

📝 Suggested documentation

 /**
- *
- * `@param` request
+ * GET /api/research/radio
+ * Returns the list of radio stations tracked by Chartmetric.
+ * Requires authentication and deducts 5 credits.
+ *
+ * `@param` request - The incoming Next.js request
+ * `@returns` JSON response with { status: "success", stations: Array } or error
  */
 export async function GET(request: NextRequest) {
   return getResearchRadioHandler(request);
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/research/radio/route.ts` around lines 12 - 18, Add a descriptive
JSDoc block above the exported async function GET that explains this endpoint's
purpose (e.g., "Handles GET requests for the research radio endpoint"),
describes the request parameter (NextRequest) and any expected query params or
headers, and documents the return value (the Response returned by
getResearchRadioHandler). Update the JSDoc to reference the handler function
name getResearchRadioHandler and include tags like `@param` and `@returns` so
readers and editors can quickly understand inputs/outputs.

lib/mcp/tools/research/registerResearchCitiesTool.ts-1-1 (1)

1-1: ⚠️ Potential issue | 🟡 Minor

Address Prettier formatting failure.

The pipeline indicates a Prettier formatting check failure. Run prettier --write on this file to resolve.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/mcp/tools/research/registerResearchCitiesTool.ts` at line 1, Prettier
formatting failed for this file; run the formatter (e.g., prettier --write) on
the file containing the import of McpServer (the import statement "import {
McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\"") or apply Prettier
rules to fix whitespace/quoting/newline issues so the file conforms to project
Prettier settings; after formatting, re-run the pipeline to confirm the Prettier
check passes.

lib/mcp/tools/research/registerResearchSimilarTool.ts-75-79 (1)

75-79: ⚠️ Potential issue | 🟡 Minor

Response normalization differs from the HTTP handler.

The HTTP handler (getResearchSimilarHandler.ts lines 37-42) returns total unconditionally from the data object, while this MCP tool conditionally omits total when data is an array. This inconsistency could cause confusion for consumers expecting identical shapes from both interfaces.

Consider aligning the normalization logic:

♻️ Suggested alignment with HTTP handler

        const data = result.data as Record<string, unknown>;
        return getToolResultSuccess({
          artists: Array.isArray(data) ? data : data?.data || [],
-         total: Array.isArray(data) ? undefined : data?.total,
+         total: (data as Record<string, unknown>)?.total,
        });

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/mcp/tools/research/registerResearchSimilarTool.ts` around lines 75 - 79,
The tool's response normalization in registerResearchSimilarTool (around the
getToolResultSuccess call) diverges from the HTTP handler
getResearchSimilarHandler by conditionally omitting total when data is an array;
change the normalization to match the HTTP handler by always returning total
from the data object (use data?.total) and keep artists computed as
Array.isArray(data) ? data : data?.data || [], so getToolResultSuccess returns
the same shape as the HTTP handler.

lib/mcp/tools/research/registerResearchChartsTool.ts-44-62 (1)

44-62: ⚠️ Potential issue | 🟡 Minor

MCP tools lack credit deduction—a pattern across all tools, not just charts.

The HTTP handler deducts 5 credits via handleResearchRequest, but this MCP tool (and all others in lib/mcp/tools/) skip credit deduction entirely. This architectural inconsistency between HTTP and MCP interfaces creates a potential credit-bypass path. Consider whether MCP tools should share the same credit deduction logic as their HTTP counterparts for billing consistency.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/mcp/tools/research/registerResearchChartsTool.ts` around lines 44 - 62,
The MCP tool handler in registerResearchChartsTool.ts currently calls
proxyToChartmetric and returns getToolResultSuccess/getToolResultError without
deducting credits; add a call to the shared credit-deduction routine (reuse
handleResearchRequest or its underlying deductCredits function) at the start of
the async (args) handler (or wrap the proxy call in handleResearchRequest) so
the same 5-credit deduction occurs for MCP requests; locate the anonymous async
handler, proxyToChartmetric, and the getToolResultSuccess/getToolResultError
calls and ensure the credit deduction runs before the external call and that
failures still return getToolResultError while not double-deducting.

lib/mcp/tools/research/registerResearchUrlsTool.ts-34-35 (1)

34-35: ⚠️ Potential issue | 🟡 Minor

Missing status check on proxyToChartmetric result.

Per the proxyToChartmetric contract (see lib/research/proxyToChartmetric.ts:5-52), non-200 responses return { data: { error: string }, status: number } without throwing. The current implementation returns result.data unconditionally, which could surface Chartmetric error payloads as successful tool results.

🛡️ Suggested fix to check status

         const result = await proxyToChartmetric(`/artist/${resolved.id}/urls`);
+        if (result.status !== 200) {
+          return getToolResultError(
+            `Request failed with status ${result.status}`,
+          );
+        }
         return getToolResultSuccess(result.data);

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/mcp/tools/research/registerResearchUrlsTool.ts` around lines 34 - 35, The
call to proxyToChartmetric in registerResearchUrlsTool returns a non-throwing
result object with status and data; update the code in the function that calls
proxyToChartmetric(`/artist/${resolved.id}/urls`) to check result.status === 200
before returning getToolResultSuccess(result.data), and when status is not 200
return a failure via getToolResultError (or similar error-return helper)
including the Chartmetric error payload (e.g., result.data.error) and the status
so callers don't treat error responses as successes.

lib/mcp/tools/research/registerResearchAudienceTool.ts-41-44 (1)

41-44: ⚠️ Potential issue | 🟡 Minor

Missing status check on proxyToChartmetric result.

Same issue as in registerResearchUrlsTool.ts — the result status isn't checked before returning data, which could propagate Chartmetric error payloads as successful tool responses.

🛡️ Suggested fix

         const result = await proxyToChartmetric(
           `/artist/${resolved.id}/${platform}-audience-stats`,
         );
+        if (result.status !== 200) {
+          return getToolResultError(
+            `Request failed with status ${result.status}`,
+          );
+        }
         return getToolResultSuccess(result.data);

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/mcp/tools/research/registerResearchAudienceTool.ts` around lines 41 - 44,
The call to proxyToChartmetric in registerResearchAudienceTool.ts returns a
response object whose HTTP status isn't checked, so Chartmetric errors can be
returned as successes; update the code after calling
proxyToChartmetric(`/artist/${resolved.id}/${platform}-audience-stats`) to
inspect result.status (or equivalent), and if it indicates failure return a
failure tool response (e.g., via getToolResultFailure with the status and error
payload) otherwise return getToolResultSuccess(result.data); mirror the same
status-check pattern used in registerResearchUrlsTool.ts and reference
proxyToChartmetric and getToolResultSuccess/getToolResultFailure to locate where
to change.

lib/mcp/tools/research/registerResearchCareerTool.ts-34-37 (1)

34-37: ⚠️ Potential issue | 🟡 Minor

Missing status check on proxyToChartmetric result.

Consistent with the pattern in other MCP tools in this PR, the status code isn't validated before returning data. Add a status check for robustness.

🛡️ Suggested fix

         const result = await proxyToChartmetric(
           `/artist/${resolved.id}/career`,
         );
+        if (result.status !== 200) {
+          return getToolResultError(
+            `Request failed with status ${result.status}`,
+          );
+        }
         return getToolResultSuccess(result.data);

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/mcp/tools/research/registerResearchCareerTool.ts` around lines 34 - 37,
The call to proxyToChartmetric in registerResearchCareerTool returns a response
whose HTTP status is not being validated before using result.data; update the
handler to check the response status (e.g., ensure result.status === 200 or a
success-range) and only call getToolResultSuccess(result.data) on success,
otherwise return an error path (e.g., getToolResultFailure or a similar failure
helper) including the status and error payload; locate the proxyToChartmetric
call and the return of getToolResultSuccess in registerResearchCareerTool to add
this status check and appropriate failure return.

lib/research/postResearchEnrichHandler.ts-23-47 (1)

23-47: ⚠️ Potential issue | 🟡 Minor

Add validation for processor parameter.

The body.processor type annotation suggests "base" | "core" | "ultra", but there's no runtime validation. Invalid values silently default to 5 credits (line 47). The MCP tool counterpart uses z.enum(["base", "core", "ultra"]) for strict validation—this handler should be consistent.

🛡️ Suggested validation

+  const validProcessors = ["base", "core", "ultra"] as const;
+  const processor = body.processor && validProcessors.includes(body.processor) 
+    ? body.processor 
+    : "base";
+
-  const creditCost = body.processor === "ultra" ? 25 : body.processor === "core" ? 10 : 5;
+  const creditCost = processor === "ultra" ? 25 : processor === "core" ? 10 : 5;

   try {
     await deductCredits({ accountId, creditsToDeduct: creditCost });

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/research/postResearchEnrichHandler.ts` around lines 23 - 47, Add runtime
validation for body.processor to ensure it is one of "base" | "core" | "ultra"
before computing creditCost: check the parsed request body (body.processor) and
if it's missing or not one of the allowed strings return a 400 JSON response
(similar style to the input/schema checks). Then compute creditCost using the
validated value (the existing creditCost expression referencing body.processor)
so invalid values don't silently fall back to 5. Use the same error/response
pattern and headers as the other early-return validations in
postResearchEnrichHandler.

lib/parallel/enrichEntity.ts-1-1 (1)

1-1: ⚠️ Potential issue | 🟡 Minor

Run Prettier to fix formatting.

Pipeline indicates Prettier check failed. Run prettier --write on this file to resolve.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/parallel/enrichEntity.ts` at line 1, Reformat this file with the
project's Prettier settings (run `prettier --write`) to fix the formatting error
reported by CI; specifically ensure the top-level constant PARALLEL_BASE_URL and
surrounding code are reformatted to match the repo style so Prettier checks
pass.

lib/mcp/tools/research/registerResearchPlaylistsTool.ts-1-1 (1)

1-1: ⚠️ Potential issue | 🟡 Minor

Run Prettier to fix formatting.

Pipeline indicates Prettier check failed. Run prettier --write on this file to resolve.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/mcp/tools/research/registerResearchPlaylistsTool.ts` at line 1, Run
Prettier to fix formatting for this file: reformat the file (e.g., run `prettier
--write`) so the import line "import { McpServer } from
"@modelcontextprotocol/sdk/server/mcp.js";" and the rest of
registerResearchPlaylistsTool.ts conform to the project's Prettier rules; commit
the reformatted file to resolve the pipeline Prettier check failure.

app/api/research/rank/route.ts (1)

5-7: Replace empty JSDoc blocks with meaningful route documentation.

Line 5 and Line 12 docblocks are empty; add concise endpoint/method/param descriptions.

As per coding guidelines app/api/**/route.ts: "All API routes should have JSDoc comments".

Also applies to: 12-15

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/research/rank/route.ts` around lines 5 - 7, The empty JSDoc blocks
above the route handler need to be replaced with concise route documentation:
add a short JSDoc before the exported route handler(s) (e.g., the
GET/POST/handler function name used in this file) describing the endpoint path,
HTTP method, expected query/body parameters, and the response shape/status
codes; also update the second empty block (lines ~12-15) with param descriptions
and an example response or error conditions so the file complies with the API
route documentation guideline.

lib/mcp/tools/research/registerResearchInstagramPostsTool.ts (1)

34-37: Consider normalizing response shape for consistency.

Other collection-returning tools (research_tracks, research_albums, research_insights) normalize responses into { [collection]: Array }. This tool returns result.data directly, which may yield inconsistent response shapes across the research tool family.

If the Instagram data structure permits, consider normalizing to { posts: Array.isArray(data) ? data : [] } for a more predictable API.

♻️ Optional normalization

         const result = await proxyToChartmetric(
           `/SNS/deepSocial/cm_artist/${resolved.id}/instagram`,
         );
-        return getToolResultSuccess(result.data);
+        const data = result.data;
+        return getToolResultSuccess({
+          posts: Array.isArray(data) ? data : [],
+        });

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/mcp/tools/research/registerResearchInstagramPostsTool.ts` around lines 34
- 37, The Instagram tool currently returns result.data directly which causes
inconsistent shapes vs other research tools; inside the
registerResearchInstagramPostsTool handler (the block calling proxyToChartmetric
and getToolResultSuccess) normalize the response to an object like { posts:
Array.isArray(result.data) ? result.data : [] } (or appropriate property name if
Instagram uses a different key) and pass that normalized object into
getToolResultSuccess so the tool returns a consistent collection-shaped payload.

lib/research/getResearchRadioHandler.ts (1)

20-27: Consider distinguishing credit deduction errors.

The current implementation catches all exceptions from deductCredits and returns 402 with "Insufficient credits". If deductCredits can throw for other reasons (e.g., database errors), this may mask the actual failure.

♻️ More precise error handling

   try {
     await deductCredits({ accountId, creditsToDeduct: 5 });
-  } catch {
+  } catch (error) {
+    const isInsufficientCredits = error instanceof Error && 
+      error.message.includes("Insufficient");
     return NextResponse.json(
-      { status: "error", error: "Insufficient credits" },
-      { status: 402, headers: getCorsHeaders() },
+      { status: "error", error: isInsufficientCredits ? "Insufficient credits" : "Credit deduction failed" },
+      { status: isInsufficientCredits ? 402 : 500, headers: getCorsHeaders() },
     );
   }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/research/getResearchRadioHandler.ts` around lines 20 - 27, Catch the
error thrown by deductCredits({ accountId, creditsToDeduct: 5 }) into a variable
and distinguish insufficient-credit failures from other failures: check for a
specific error marker (e.g., error instanceof InsufficientCreditsError,
error.name === 'InsufficientCreditsError', or error.code ===
'INSUFFICIENT_CREDITS') and return the 402 NextResponse.json({ status: "error",
error: "Insufficient credits" }, ...) only in that case; for other errors, log
or capture the error and return a 500 NextResponse.json({ status: "error",
error: "Internal server error" }, ...) (or rethrow) so database/unknown errors
are not masked. Ensure references to deductCredits and the surrounding try/catch
in getResearchRadioHandler.ts are updated accordingly.

lib/mcp/tools/research/index.ts (1)

28-29: Minor: Missing blank line before JSDoc.

There's no blank line between the last import (line 28) and the JSDoc comment (line 29). This is a minor formatting inconsistency but may be caught by the linter.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/mcp/tools/research/index.ts` around lines 28 - 29, Minor formatting: add
a single blank line between the last import statement (import {
registerResearchRadioTool } from "./registerResearchRadioTool";) and the
following JSDoc block so the JSDoc is separated from imports; update the top of
lib/mcp/tools/research/index.ts by inserting one empty line between that import
and the /** JSDoc comment to satisfy linter/style rules.

app/api/research/charts/route.ts (1)

5-10: JSDoc comments are incomplete.

The JSDoc blocks are present but lack descriptions. Per coding guidelines, all API routes should have JSDoc comments. Consider adding meaningful descriptions for both handlers.

📝 Suggested documentation

 /**
- *
+ * OPTIONS handler for CORS preflight requests.
  */
 export async function OPTIONS() {
   return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
 }

 /**
- *
- * `@param` request
+ * GET /api/research/charts
+ *
+ * Returns global chart positions for a given platform (Spotify, Apple Music, etc.).
+ *
+ * `@param` request - The incoming Next.js request object
  */
 export async function GET(request: NextRequest) {
   return getResearchChartsHandler(request);
 }

Also applies to: 12-18

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/research/charts/route.ts` around lines 5 - 10, The JSDoc blocks for
the API route handlers (e.g., the exported async function OPTIONS and the other
handlers around that block) are empty—add concise JSDoc comments above each
exported handler describing what the route/handler does, its expected inputs or
purpose, and the response (e.g., "Handles CORS preflight requests and returns
200 with CORS headers" for OPTIONS); apply the same pattern to the other
handlers in this file so each exported function has a meaningful description,
parameters/returns notes if applicable, and any relevant behavior details.

lib/research/getResearchChartsHandler.ts (2)

20-51: Consider using Zod schema for input validation.

Per coding guidelines, all API endpoints should use a validate function with Zod for input parsing. Currently, parameters are manually extracted without schema validation. This would improve type safety and provide better error messages.

♻️ Suggested Zod schema approach

import { z } from "zod";

const chartsQuerySchema = z.object({
  platform: z.string().min(1, "platform parameter is required"),
  country: z.string().optional(),
  interval: z.string().optional(),
  type: z.string().optional(),
  latest: z.string().default("true"),
});

// Then in handler:
const parseResult = chartsQuerySchema.safeParse(Object.fromEntries(searchParams));
if (!parseResult.success) {
  return NextResponse.json(
    { status: "error", error: parseResult.error.issues[0].message },
    { status: 400, headers: getCorsHeaders() },
  );
}
const { platform, country, interval, type, latest } = parseResult.data;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/research/getResearchChartsHandler.ts` around lines 20 - 51, Replace
manual query extraction with Zod-based validation: define a chartsQuerySchema
(using z.object with platform: z.string().min(1), country/interval/type
optional, latest default "true") and run safeParse/validate on
Object.fromEntries(searchParams) at the top of getResearchChartsHandler; if
validation fails return a 400 NextResponse.json with the validation message and
getCorsHeaders(), and only after successful parse call deductCredits({
accountId, creditsToDeduct: 5 }); then use parsed fields (platform, country,
interval, type, latest) to populate params instead of reading searchParams
directly. Ensure you reference chartsQuerySchema, searchParams, NextResponse,
getCorsHeaders, and deductCredits when making the change.

---

62-65: Response structure uses nested data wrapper.

The coding guidelines specify to keep API response bodies flat with fields at the root level, not nested inside a data wrapper. However, this pattern appears consistent with other research handlers in this PR. If this is intentional for this endpoint family, consider documenting the exception.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/research/getResearchChartsHandler.ts` around lines 62 - 65, The response
body currently nests the payload under a data property (in the return inside
getResearchChartsHandler), violating the flat-root response convention; change
the NextResponse.json call to place fields from result.data at the root (e.g.,
return { status: "success", ...result.data }) instead of { status: "success",
data: result.data }, and if the nested pattern is intentional for the research
handlers, update or add a short note in docs or a comment to justify the
exception and make the pattern consistent across related handlers.

lib/mcp/tools/research/registerResearchAudienceTool.ts (1)

40-40: Redundant fallback — Zod default already provides "instagram".

The schema at line 13 uses .default("instagram"), so args.platform will never be undefined after Zod parsing. The ?? "instagram" fallback is defensive but unnecessary.

✂️ Simplification

-        const platform = args.platform ?? "instagram";
+        const platform = args.platform;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/mcp/tools/research/registerResearchAudienceTool.ts` at line 40, The
fallback is redundant because the Zod schema already sets a default; replace the
defensive expression by using args.platform directly (remove the "??
'instagram'" from the const assignment) in the registerResearchAudienceTool code
so the variable simply reads the parsed value from args.platform; ensure no
other code assumes undefined for platform.

lib/mcp/tools/research/registerResearchEnrichTool.ts (1)

43-43: Redundant fallback — Zod default already provides "base".

The schema at line 15 uses .default("base"), so args.processor will always be defined after parsing. The ?? "base" fallback is unnecessary.

✂️ Simplification

-          args.processor ?? "base",
+          args.processor,

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/mcp/tools/research/registerResearchEnrichTool.ts` at line 43, Remove the
redundant fallback by deleting the `?? "base"` after `args.processor` in the
call site (the `args.processor ?? "base"` expression) since the Zod schema
already sets a default of "base"; update the code in the
registerResearchEnrichTool usage to pass `args.processor` directly (referencing
the `args.processor` symbol and the surrounding function
`registerResearchEnrichTool`) so the value comes from the parsed args without an
extra fallback.

app/api/research/milestones/route.ts (1)

5-15: Empty JSDoc comments provide no documentation value.

The JSDoc blocks for both OPTIONS and GET handlers are empty placeholders. As per coding guidelines, all API routes should have meaningful JSDoc comments describing the endpoint's purpose, parameters, and response.

📝 Suggested JSDoc improvements

 /**
- *
+ * OPTIONS handler for CORS preflight requests.
  */
 export async function OPTIONS() {
   return new NextResponse(null, { status: 200, headers: getCorsHeaders() });
 }

 /**
- *
- * `@param` request
+ * GET /api/research/milestones
+ *
+ * Returns an artist's activity feed — playlist adds, chart entries,
+ * and other notable events tracked by Chartmetric.
+ *
+ * `@param` request - The incoming request with artist query parameter
  */
 export async function GET(request: NextRequest) {

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/research/milestones/route.ts` around lines 5 - 15, The file contains
empty JSDoc blocks for the API route handlers; update the JSDoc for the exported
handlers (OPTIONS and GET in route.ts) to provide a concise description of the
endpoint's purpose, the incoming parameters (e.g., Request or query params), and
the expected response shape/status codes; reference the OPTIONS and GET
functions and include notes about CORS headers (getCorsHeaders) in the docs so
consumers and maintainers understand behavior and responses.

lib/research/getResearchMilestonesHandler.ts (1)

12-18: Consider defining a type for the Chartmetric response.

The (data as any)?.insights cast works but loses type safety. A minimal interface would improve maintainability and IDE support without significant effort.

🔧 Optional type improvement

+interface MilestonesResponse {
+  insights?: unknown[];
+}
+
 export async function getResearchMilestonesHandler(request: NextRequest) {
   return handleArtistResearch(
     request,
     (cmId) => `/artist/${cmId}/milestones`,
     undefined,
-    (data) => ({ milestones: (data as any)?.insights || [] }),
+    (data) => ({ milestones: (data as MilestonesResponse)?.insights || [] }),
   );
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/research/getResearchMilestonesHandler.ts` around lines 12 - 18, Replace
the untyped cast in getResearchMilestonesHandler by introducing a minimal
interface for the Chartmetric response (e.g. ChartmetricMilestonesResponse with
an insights: Milestone[] field) and use that type instead of any; update the
mapping callback passed to handleArtistResearch to expect
ChartmetricMilestonesResponse and return { milestones: response.insights || [] }
(or make handleArtistResearch generic so you can call
handleArtistResearch<ChartmetricMilestonesResponse>(...)). This preserves type
safety while keeping the transformation logic in getResearchMilestonesHandler
and requires adding the new interface (and optional Milestone type) and, if
necessary, a generic parameter on handleArtistResearch.

lib/mcp/tools/research/registerResearchMetricsTool.ts (1)

10-14: Consider using z.enum() for platform validation consistency.

The sibling tool registerResearchAudienceTool uses z.enum(["instagram", "tiktok", "youtube"]) to constrain platform values at the schema level. Here, source accepts any string and is interpolated directly into the URL path at line 42. While Chartmetric will reject invalid platforms, schema-level validation provides better error messages and consistency across tools.

♻️ Suggested improvement

 const schema = z.object({
   artist: z.string().describe("Artist name to research"),
   source: z
-    .string()
+    .enum([
+      "spotify",
+      "instagram",
+      "tiktok",
+      "youtube_channel",
+      "soundcloud",
+      "deezer",
+      "twitter",
+      "facebook",
+    ])
     .describe(
       "Platform: spotify, instagram, tiktok, youtube_channel, soundcloud, deezer, twitter, facebook, etc.",
     ),
 });

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/mcp/tools/research/registerResearchMetricsTool.ts` around lines 10 - 14,
The schema for `source` in `registerResearchMetricsTool` currently uses
`z.string()` and should be tightened to a `z.enum()` that lists the allowed
platforms (the same set used by `registerResearchAudienceTool`, e.g.,
"instagram", "tiktok", "youtube", etc.) so invalid platform values are rejected
at schema validation instead of only by the downstream Chartmetric call; update
the `source` schema to `z.enum([...])`, keep the descriptive text, and ensure
any code that reads `source` (the URL path interpolation) continues to work with
the enum values.

lib/research/postResearchExtractHandler.ts (1)

46-53: Consider preserving the original error message from deductCredits.

The deductCredits function throws with specific messages (e.g., "No credits usage found for this account" vs "Insufficient credits. Required: X, Available: Y"). Catching all exceptions as "Insufficient credits" loses diagnostic information.

♻️ Preserve error detail

   try {
     await deductCredits({ accountId, creditsToDeduct: 5 * body.urls.length });
   } catch {
+  } catch (error) {
     return NextResponse.json(
-      { status: "error", error: "Insufficient credits" },
+      { status: "error", error: error instanceof Error ? error.message : "Insufficient credits" },
       { status: 402, headers: getCorsHeaders() },
     );
   }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/research/postResearchExtractHandler.ts` around lines 46 - 53, The catch
for deductCredits currently swallows the original error; change the try/catch to
catch the error (e.g., catch (err)) and return the NextResponse.json error
payload using the original message (e.g., error: err?.message || String(err) ||
"Insufficient credits") while keeping the 402 status and getCorsHeaders; update
references in this block (deductCredits, accountId, creditsToDeduct,
NextResponse.json, getCorsHeaders) so diagnostic details from deductCredits are
preserved safely.

lib/mcp/tools/research/registerResearchRankTool.ts (1)

38-38: Consider using nullish coalescing for rank extraction.

Using || null will convert a rank of 0 to null. While Chartmetric ranks are typically 1-indexed, using ?? null is more defensive and semantically correct for "missing value" scenarios.

♻️ Minor fix

-        const rank = (result.data as any)?.artist_rank || null;
+        const rank = (result.data as any)?.artist_rank ?? null;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/mcp/tools/research/registerResearchRankTool.ts` at line 38, The current
extraction uses const rank = (result.data as any)?.artist_rank || null which
will coerce a valid 0 rank to null; change the fallback to the nullish
coalescing operator so use (result.data as any)?.artist_rank ?? null instead —
update the declaration of rank in registerResearchRankTool (the const rank
binding that reads result.data.artist_rank) to use ?? null so only
null/undefined become null while preserving numeric 0.

lib/parallel/enrichEntity.ts (3)

80-86: Consider defensive type check for output.basis.

The output?.basis || [] handles undefined, but if basis exists but isn't an array (API contract change), flatMap will throw. A defensive check improves resilience:

🛡️ Defensive type guard

-  const citations = (output?.basis || []).flatMap(
+  const basisArray = Array.isArray(output?.basis) ? output.basis : [];
+  const citations = basisArray.flatMap(

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/parallel/enrichEntity.ts` around lines 80 - 86, The code assumes
output.basis is an array when building citations from resultData.output; add a
defensive type guard before using flatMap: verify output exists and
Array.isArray(output.basis) (or coerce to an empty array) to avoid runtime
errors if basis is present but not an array. Update the citations computation
(referencing resultData, output, and the citations variable) to use the
guarded/normalized basis value so flatMap is only called on a true array.

---

55-60: Add type safety for the task creation response.

The response from createResponse.json() is untyped. Consider adding a minimal type assertion or validation to ensure run_id exists with the expected type.

♻️ Type-safe response handling

-  const taskRun = await createResponse.json();
-  const runId = taskRun.run_id;
+  const taskRun = (await createResponse.json()) as { run_id?: string };
+  const runId = taskRun.run_id;

Or for stricter validation:

interface TaskRunResponse {
  run_id: string;
}

const taskRun: TaskRunResponse = await createResponse.json();

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/parallel/enrichEntity.ts` around lines 55 - 60, The code reads an untyped
JSON from createResponse.json() and then accesses run_id (taskRun and runId);
add type safety by defining a minimal interface (e.g., TaskRunResponse { run_id:
string }) and assert/validate the parsed JSON against it, or perform a runtime
check that taskRun has a string run_id before assigning runId, throwing a clear
error if validation fails; apply this change around the createResponse.json()
call and the taskRun/runId variables to ensure type-safe handling.

---

20-94: Function exceeds 50-line guideline.

At ~74 lines, this function exceeds the coding guideline suggesting functions stay under 50 lines. Consider extracting the task creation (lines 32-60) and result polling (lines 62-93) into separate private helpers if this module grows.

As per coding guidelines: "Keep functions under 50 lines."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/parallel/enrichEntity.ts` around lines 20 - 94, The enrichEntity function
is over the 50-line guideline—extract the task creation and result fetching
logic into two private helpers to reduce size: move the POST-to-/tasks/runs
block (currently creating createResponse, checking createResponse.ok, parsing
taskRun and runId) into a helper named e.g. createParallelTaskRun(input,
outputSchema, processor, apiKey) and move the GET-to-/tasks/runs/{runId}/result
logic (timeout/404/other error handling, parsing resultData, building output and
citations) into a helper named e.g. fetchParallelTaskResult(runId, timeout,
apiKey); then have enrichEntity call those two helpers and return the final
EnrichResult, preserving existing error messages and behavior.

lib/parallel/extractUrl.ts (2)

56-56: Redundant await in return statement.

The await before response.json() is unnecessary when immediately returning. The async function already wraps the return value in a Promise.

♻️ Minor cleanup

-  return await response.json();
+  return response.json();

Note: Some style guides prefer explicit await for consistency in error stack traces. This is a minor preference.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/parallel/extractUrl.ts` at line 56, Remove the redundant await in the
return statement: replace the explicit "return await response.json()" inside the
async function (the function containing the response.json() call in
lib/parallel/extractUrl.ts) with "return response.json()" so the async function
directly returns the Promise from response.json().

---

22-24: Input constraints documented but not validated.

The JSDoc mentions "max 10 per request" for URLs and "max 3000 chars" for objective, but these aren't validated before the API call. Consider adding validation to fail fast with clear errors:

🛡️ Add input validation

 export async function extractUrl(
   urls: string[],
   objective?: string,
   fullContent: boolean = false,
 ): Promise<ExtractResponse> {
+  if (urls.length === 0) {
+    throw new Error("At least one URL is required");
+  }
+  if (urls.length > 10) {
+    throw new Error("Maximum 10 URLs allowed per request");
+  }
+  if (objective && objective.length > 3000) {
+    throw new Error("Objective must be 3000 characters or fewer");
+  }
+
   const apiKey = process.env.PARALLEL_API_KEY;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/parallel/extractUrl.ts` around lines 22 - 24, The JSDoc limits (max 10
URLs and max 3000 chars for objective) are not enforced; update the exported
function (e.g., extractUrl or extractUrls in lib/parallel/extractUrl.ts) to
validate inputs up-front: check that urls is an array with 1–10 items, that each
item is a string (optionally validate via new URL(...) to ensure well-formed
URLs), and that objective, if provided, is a string of length ≤3000; if any
check fails, throw a clear, synchronous error (or return a rejected Promise)
with a descriptive message before making the API call so callers fail fast.

lib/mcp/tools/research/registerResearchPlaylistsTool.ts (2)

60-67: Filter behavior differs when editorial is explicitly provided.

When editorial is explicitly set (true or false), only that filter is sent. This means:

• editorial: true → only editorial playlists (loses indie, majorCurator, popularIndie)
• editorial: false → sends editorial=false without other filters

Compare with the REST handler in getResearchPlaylistsHandler.ts which supports indie, majorCurator, personalized, and chart filters individually. If this is intentional simplification for MCP, consider documenting it. Otherwise, exposing additional filter options would provide parity.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/mcp/tools/research/registerResearchPlaylistsTool.ts` around lines 60 -
67, Current behavior in registerResearchPlaylistsTool (the args -> queryParams
block) only sends the editorial filter when args.editorial is defined, dropping
indie/majorCurator/popularIndie; update the logic so that when args.editorial is
provided you still populate other filter query params from args if present
(e.g., args.indie, args.majorCurator, args.popularIndie, and any supported
personalized/chart flags) instead of overwriting them, mirroring the behavior in
getResearchPlaylistsHandler.ts; locate the conditional around args.editorial and
change it to set queryParams.editorial = String(args.editorial) while also
conditionally setting queryParams.indie, queryParams.majorCurator,
queryParams.popularIndie (and personalized/chart if supported) from args when
those fields are present, or document the intentional simplification if parity
is not desired.

---

24-28: The limit default makes the conditional on line 58 always true.

Since limit has .default(20), args.limit will always be defined and truthy (20). The conditional if (args.limit) on line 58 will always evaluate to true, so limit is always included in queryParams.

This works correctly but is misleading. Consider removing the conditional for clarity:

♻️ Clearer implementation

         const queryParams: Record<string, string> = {};
-        if (args.limit) queryParams.limit = String(args.limit);
+        queryParams.limit = String(args.limit);

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/mcp/tools/research/registerResearchPlaylistsTool.ts` around lines 24 -
28, The conditional "if (args.limit)" is misleading because args.limit always
has a default 20; update registerResearchPlaylistsTool to always include the
limit param instead of conditionally adding it: remove the "if (args.limit)"
guard and assign queryParams.limit = args.limit (or otherwise ensure queryParams
includes args.limit unconditionally). This keeps the z schema default behavior
and makes the intent explicit by using args.limit and queryParams directly.